package com.smart.community.work.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.work.dto.LeaveQueryDTO;
import com.smart.community.work.entity.Leave;
import com.smart.community.work.vo.LeaveVO;

import java.time.LocalDate;
import java.util.List;
import java.util.Map;

/**
 * 请假管理服务接口
 * 
 * 严格按照《Java后端SpringBoot代码开发规范_重构版.md》Service规范实现：
 * - 继承IService：获得基础CRUD方法
 * - 方法命名：使用动词+名词形式，语义明确
 * - 参数验证：使用@Valid注解进行参数验证
 * - 异常处理：使用统一的异常处理机制
 * - 完整注释：所有方法都有完整的JavaDoc注释
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 * @version 1.0.0
 */
public interface LeaveService extends IService<Leave> {

    /**
     * 分页查询请假记录（已废弃，使用selectLeavePageWithPermission替代）
     * 
     * @param page 分页参数
     * @param params 查询参数
     * @return 请假记录分页数据
     * @deprecated 使用selectLeavePageWithPermission替代
     */
    @Deprecated
    IPage<LeaveVO> selectLeavePage(Page<LeaveVO> page, Map<String, Object> params) throws Exception;

    /**
     * 分页查询请假记录（支持数据权限控制）
     * 
     * @param page 分页参数
     * @param queryDTO 查询参数
     * @param currentUserId 当前登录用户ID
     * @return 请假记录分页数据
     */
    IPage<LeaveVO> selectLeavePageWithPermission(Page<LeaveVO> page, LeaveQueryDTO queryDTO, Long currentUserId) throws Exception;

    /**
     * 获取请假详情
     * 
     * @param id 请假记录ID
     * @param currentUserId 当前登录用户ID
     * @return 请假记录详情
     */
    LeaveVO getLeaveDetail(Long id, Long currentUserId) throws Exception;

    /**
     * 根据用户ID查询请假记录
     * 
     * @param userId 用户ID
     * @param propertyCompanyId 物业公司ID
     * @return 请假记录列表
     */
    List<LeaveVO> selectByUserId(Long userId, Long propertyCompanyId) throws Exception;

    /**
     * 根据审批人ID查询待审批请假记录
     * 
     * @param approverId 审批人ID
     * @param propertyCompanyId 物业公司ID
     * @return 待审批请假记录列表
     */
    List<LeaveVO> selectPendingByApproverId(Long approverId, Long propertyCompanyId) throws Exception;

    /**
     * 申请请假
     * 
     * @param leave 请假记录
     * @return 申请结果
     */
    Boolean applyLeave(Leave leave) throws Exception;

    /**
     * 审批请假
     * 
     * @param id 请假ID
     * @param status 审批状态
     * @param approverId 审批人ID
     * @param approveRemark 审批备注
     * @return 审批结果
     */
    Boolean approveLeave(Long id, Integer status, Long approverId, String approveRemark) throws Exception;

    /**
     * 撤销请假申请
     * 
     * @param id 请假ID
     * @param userId 用户ID
     * @return 撤销结果
     */
    Boolean cancelLeave(Long id, Long userId) throws Exception;

    /**
     * 统计请假数据
     * 
     * @param propertyCompanyId 物业公司ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 请假统计
     */
    Map<String, Object> getLeaveStatistics(Long propertyCompanyId, LocalDate startDate, LocalDate endDate) throws Exception;

    /**
     * 统计各状态请假数量
     * 
     * @param propertyCompanyId 物业公司ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 状态统计
     */
    List<Map<String, Object>> getLeaveStatusStatistics(Long propertyCompanyId, LocalDate startDate, LocalDate endDate) throws Exception;

    /**
     * 更新请假状态
     * 
     * @param id 请假ID
     * @param status 状态
     * @param updateBy 更新人ID
     * @return 更新结果
     */
    Boolean updateStatus(Long id, Integer status, Long updateBy) throws Exception;

    /**
     * 批量更新请假状态
     * 
     * @param ids 请假ID列表
     * @param status 状态
     * @param updateBy 更新人ID
     * @return 更新结果
     */
    Boolean batchUpdateStatus(List<Long> ids, Integer status, Long updateBy) throws Exception;

    /**
     * 删除请假记录
     * 
     * @param id 请假ID
     * @param updateBy 更新人ID
     * @return 删除结果
     */
    Boolean deleteById(Long id, Long updateBy) throws Exception;

    /**
     * 批量删除请假记录
     * 
     * @param ids 请假ID列表
     * @param updateBy 更新人ID
     * @return 删除结果
     */
    Boolean batchDelete(List<Long> ids, Long updateBy) throws Exception;

    /**
     * 根据物业公司ID列表查询保洁人员列表
     * 
     * @param propertyCompanyIds 物业公司ID列表
     * @return 保洁人员用户ID列表
     */
    List<Long> getCleaningStaffUserIds(List<Long> propertyCompanyIds) throws Exception;

    /**
     * 根据物业公司ID列表查询安保人员列表
     * 
     * @param propertyCompanyIds 物业公司ID列表
     * @return 安保人员用户ID列表
     */
    List<Long> getSecurityStaffUserIds(List<Long> propertyCompanyIds) throws Exception;
}